# Worldview

## Props

| Name                  | Type                                            | Default                | Description                                                                                             |
| --------------------- | ----------------------------------------------- | ---------------------- | ------------------------------------------------------------------------------------------------------- |
| `cameraState`         | `$Shape<CameraState>`                           |                        | control the [cameraState](#/docs/api/camera), must use with `onCameraStateChange`                       |
| `onCameraStateChange` | `(CameraState) => void`                         |                        | callback whenever the camera state changes                                                              |
| `defaultCameraState`  | `$Shape<CameraState>`                           | `DEFAULT_CAMERA_STATE` | pass in this prop to turn Worldview to an uncontrolled component. `onCameraStateChange` will be ignored |
| `keyMap`              | `CameraKeyMap`                                  | {}                     | override default Worldview hotkeys                                                                      |
| `shiftKeys`           | `boolean`                                       | true                   | enable/disable shift modifier for keyboard controls                                                     |
| `backgroundColor`     | `Vec4`                                          | `[0,0,0,1]`            | change the scene background color                                                                       |
| `disableHitmapForEvents`   | `[MouseEventEnum]`                         | ["onMouseMove"]    | disable rendering the hitmap for some mouse events for performance reasons. Only "onMouseMove" is disabled by default. |
| `enableStackedObjectEvents` | `boolean`                                 |                        | if enabled, event handlers will be called with all objects the mouse cursor is on top of, not just the top-most object. Disabled by default for performance reasons. |
| `children`            | `React.Node`                                    |                        | regl components to render inside the Worldview                                                          |
| `style`               | `{ [styleAttribute: string]: number | string }` | {}                     | html style object for the Worldview root element                                                        |
| `showDebug`           | `boolean`                                       |                        | show debug information                                                                                  |
| `onDoubleClick`       | `MouseHandler`                                  |                        |                                                                                                         |
| `onMouseDown`         | `MouseHandler`                                  |                        |                                                                                                         |
| `onMouseUp`           | `MouseHandler`                                  |                        |                                                                                                         |
| `onMouseMove`         | `MouseHandler`                                  |                        |                                                                                                         |
| `onClick`             | `MouseHandler`                                  |                        |                                                                                                         |
| `hitmapOnMouseMove`   | `boolean`                                       |                        | (DEPRECATED: see `disableHitmapForEvents`) if enabled, the clicked object will be returned from the mouse event handler. Disabled by default for performance reasons. |

_All props are optional._

## Mouse Event Handlers

See [MouseEvents](#/docs/api/mouse-events).

## Keyboard Controls

`keyMap` allows you to customize the keyboard controls for Worldview's camera. The `keyMap` is an optional object whose keys are [KeyboardEvent.code](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/code) values, and whose values specify the action to perform when the corresponding key is pressed. To disable a key from the keyboard controls, simply provide a `null`/`false` value for that key. For example, the following would reverse all actions and disable tilting and zooming:

    <Worldview keyMap={{
      KeyW: 'moveDown',
      KeyA: 'moveRight',
      KeyS: 'moveUp',
      KeyD: 'moveLeft',
      KeyE: 'rotateLeft',
      KeyQ: 'rotateRight',

      KeyR: false,
      KeyF: null,
      KeyX: false,
      KeyZ: null,
    }} />

When the Shift key is pressed along with keys in the `keyMap`, the motion will be slowed. To disable this behavior, pass `shiftKeys={false}`.
